.\" mintty man page
.\"
.\" This 'man' page is Copyright 2009 Lee D. Rothstein, 2009-10 Andy Koppe
.\"
.\" You may distribute, use, and modify this man page under the terms
.\" of the GNU Free Documentation License (GFDL), Version 1.3,
.\" 3 November 2008 (or later) as specified.
.TH mintty 1 2010-06-17 0.7.1 Cygwin

.ad l

.SH NAME

mintty - Cygwin terminal emulator


.SH SYNOPSIS

\fBmintty\fP [\fIOPTION\fP]... [ \fB-\fP | \fIPROGRAM\fP [\fIARG\fP]... ]


.SH DESCRIPTION

\fBMintty\fP is a terminal emulator for Cygwin with a native Windows user
interface and minimalist design.
Its terminal emulation is largely compatible with \fBxterm\fP, but it does not
require an X server.


.SH INVOCATION

If a program name is supplied on the command line, this is executed with any
additional arguments given.
Otherwise, mintty looks for a shell to execute in the \fISHELL\fP environment
variable.
If that is not set, it reads the user's default shell setting from
\fI/etc/passwd\fP.
As a last resort, it falls back to \fI/bin/sh\fP.
If a single dash is specified instead of a program name, the shell is invoked
as a login shell.


.SH OPTIONS

The standard GNU option formats are accepted, with single dashes
introducing short options and double dashes introducing long options,
e.g. \fB-o arg\fP, \fB--option arg\fP, and \fB--option=arg\fP.

.TP
\fB-e\fP, \fB--exec\fP \fIPROGRAM\fP [\fIARG\fP ...]
Execute the specified program in the terminal session and pass on any additional
arguments.
This option can be omitted, in which case the first non-option argument, if any,
is taken as the name of the program to execute.

.TP
\fB-p\fP, \fB--position\fP \fIX\fB,\fIY\fR
Open the window with its top left corner at the specified coordinates.

.TP
\fB-s\fP, \fB--size\fP \fICOLS\fB,\fIROWS\fR
Set the initial size of the window in character columns and rows.

.TP
\fB-w\fP, \fB--window\fP \fBnormal\fP|\fBmin\fP|\fBmax\fP|\fBfull\fP
Set the initial window state: normal, minimized, maximized, or full screen.

.TP
\fB-t\fP, \fB--title\fP \fITITLE\fP
Use \fITITLE\fP as the initial window title.
By default, the title is set to the executed command.

.TP
\fB--class\fP \fICLASS\fP
Use \fICLASS\fP as the window class name of the main window.
This allows scripting tools to distinguish different mintty instances.
The default is "mintty".

.TP
\fB-i\fP, \fB--icon\fP \fIFILE\fP[\fB,\fIINDEX\fR]
Load the window icon from an executable, DLL, or icon file.
A comma-separated index can be used to select an icon in a file with multiple
icons.

.TP
\fB-l\fP, \fB--log\fP \fIFILE\fP
Copy all output into the specified log file.
(See also \fIscript\fP(1) for a more flexible logging tool.)

.TP
\fB-u\fP, \fB--utmp\fP
Create a utmp entry.

.TP
\fB-h\fP, \fB--hold\fP \fBnever\fP|\fBalways\fP|\fBerror\fP
Determine whether to keep the terminal window open after the command exits.
The argument can be abbreviated to a single letter.
By default, the window is closed as soon as the child process terminates.
Alternatively, it can be set to always stay open or to stay open only if the 
child process terminates with an error, i.e. a non-zero exit code or a runtime
error signal.

.TP
\fB-c\fP, \fB--config\fP \fIFILENAME\fP
Read settings from the specified configuration file, in addition to
\fI/etc/minttyrc\fP and \fI~/.minttyrc\fP.

.TP
\fB-o\fP, \fB--option\fP \fINAME\fP=\fIVALUE\fP
Override the named config file option with the given value, e.g.
\fC-o CopyOnSelect=1\fP.

.TP
\fB-H\fP, \fB--help\fP
Display a brief help message and exit.

.TP
\fB-V\fP, \fB--version\fP
Print version information and exit.


.SH USAGE

Mintty aims to adhere to both Windows and Unix usage conventions.
Where they conflict, the Windows conventions usually take precedence.
This section primarily describes the default configuration;
see the \fBCONFIGURATION\fP section on how it can be customised.


.SS Menus

The context menu can be opened by right-clicking the mouse or by
pressing the \fBMenu\fP key that is normally located next to the right Ctrl key.

Mintty also adds a couple of items to the window menu, which can be accessed 
by clicking on the program icon or pressing \fBAlt+Space\fP.

Both menus have an entry that leads to the options dialog for changing mintty's
configuration.


.SS Copy & paste

Screen contents can be selected by holding down the left mouse button and
dragging the mouse.
The selection can be extended by holding down \fBShift\fP while left-clicking.
Double-clicking or triple-clicking selects a whole word or line, whereby word
selection includes special characters that commonly appear in file names and
URLs.

In the default configuration, selected text has to be explicitly copied
to the clipboard using either the \fBCopy\fP menu command, the
\fBCtrl+Ins\fP keyboard shortcut, or the middle mouse button combined
with \fBShift\fP.
X-like copy-on-select behaviour can be enabled on the \fBMouse\fP page of the
options dialog.

The selected region is copied as "rich text" as well as normal text,
which means it can be pasted with colours and formatting into applications
that support it, e.g. word processors.

The window title can be copied using the \fBCopy Title\fP command in the window
menu or the shortcut \fBShift+Ctrl+Ins\fP.

The clipboard contents can be pasted using either the \fBPaste\fP menu command,
the \fBShift+Ins\fP keyboard shortcut, or the middle mouse button.
Not only text but also files and directories can be pasted,
whereby the latter are inserted as Cygwin filenames.
Shell quoting is added to filenames that contain spaces or special characters.


.SS Drag & drop

Text, files and directories can be dropped into the mintty window.
They are inserted in the same way as if they were pasted from the clipboard.


.SS Opening files, directories and URLs

Files, directories and URLs can be opened either by holding \fBCtrl\fP while
left-clicking on them, or by selecting them and choosing the \fBOpen\fP
command from the context menu.
Please note that opening a file or directory with a relative path only works
correctly if the path refers to the current working directory of the process
invoked by mintty.


.SS Font zoom

The font size can be increased or decreased using the keyboard shortcuts
\fBCtrl+plus\fP and \fBCtrl+minus\fP.
\fBCtrl+zero\fP returns it to the size configured in the options dialog.


.SS Full screen

Full screen mode can be toggled using either the \fBFull Screen\fP command in
the menu or either of the \fBAlt+Enter\fP and \fBAlt+F11\fP keyboard shortcuts.


.SS Default size

If the window has been resized, it can be returned to the default size set in
the Window pane of the options using the \fBDefault size\fP command in the
menu or the \fBAlt+F10\fP shortcut.


.SS Reset

Sometimes a faulty application or printing a binary file will leave the
terminal in an unusable state. In that case, resetting the terminal's state
via the \fBReset\fP command in the menu or the \fBAlt+F8\fP keyboard shortcut
may help.


.SS Scrolling

Mintty has a scrollback buffer that can hold up to 10000 lines in the default
configuration.
It can be accessed using the scrollbar, the mouse wheel, or the keyboard.
Hold the \fBShift\fP key while pressing the \fBUp\fP and \fBDown\fP arrow keys
to scroll line-by-line or the \fBPageUp\fP and \fBPageDown\fP keys to scroll
page-by-page.


.SS Flip screen

Applications such as editors and file viewers normally use a terminal feature
called the alternate screen, which is a second screen buffer without scrollback.
When they exit, they switch back to the primary screen to restore the command
line as it was before invoking the application.

The \fBFlip Screen\fP menu command and \fBAlt+F12\fP shortcut allow looking
at the primary screen while the alternate screen is active, and vice versa.
For example, this allows to refer to past commands while editing a file.


.SS Mouse tracking

When an application activates mouse tracking, mouse events are sent to the
application rather than being treated as window events.
This is indicated by the mouse pointer changing from an \fBI\fP shape to an
arrow.
Holding down \fBShift\fP overrides mouse tracking mode and sends mouse
events to the window instead, so that e.g. text can be selected and the context
menu can be accessed.


.SS Switching session

The \fBCtrl+Tab\fP and \fBCtrl+Shift+Tab\fP shortcuts can be used to switch
between mintty windows.  Minimised windows are skipped.


.SS Closing a session

Clicking the window's close button, pressing \fBAlt+F4\fP, or choosing
\fBClose\fP from the window menu sends a \fISIGHUP\fP signal to the process
running in mintty, which normally causes it to exit.

That signal can be ignored, though, in which case the program might have to be
forced to terminate by sending a \fISIGKILL\fP signal instead.
This can be done by holding down \fBShift\fP when using the close button,
shortcut or menu item.


.SS Shortcuts

An overview of all the keyboard shortcuts.

.TP
\fBWindow commands\fP

.RS
.PD 0
.IP "\- \fBAlt+F2\fP: New"
.IP "\- \fBAlt+F4\fP: Close"
.IP "\- \fBAlt+F8\fP: Reset"
.IP "\- \fBAlt+F10\fP: Default size"
.IP "\- \fBAlt+F11\fP or \fBAlt+Enter\fP: Full screen"
.IP "\- \fBAlt+F12\fP: Flip screen"
.IP "\- \fBAlt+Space\fP: Window menu"
.IP "\- \fBCtrl+Tab\fP: Next window"
.IP "\- \fBCtrl+Shift+Tab\fP: Previous window"
.RE

.TP
\fBScrollback\fP

.RS
.PD 0
.IP "\- \fBShift+Up\fP: Line up"
.IP "\- \fBShift+Down\fP: Line down"
.IP "\- \fBShift+PgUp\fP: Page up"
.IP "\- \fBShift+PgDown\fP: Page down"
.IP "\- \fBShift+Home\fP: Top"
.IP "\- \fBShift+End\fP: Bottom"
.RE

.TP
\fBCopy and paste\fP

.RS
.PD 0
.IP "\- \fBCtrl+Ins\fP: Copy"
.IP "\- \fBShift+Ins\fP: Paste"
.RE

.TP
\fBFont zoom\fP

.RS
.PD 0
.IP "\- \fBCtrl+plus\fP: Zoom in"
.IP "\- \fBCtrl+minus\fP: Zoom out"
.IP "\- \fBCtrl+zero\fP: Back to configured font size"
.RE


.SH CONFIGURATION

Mintty has a graphical options dialog that can be reached via the context menu
or the window menu.  As usual, both \fBApply\fP and \fBOK\fP apply any changes
made, but \fBOK\fP also closes the dialog.  \fBCancel\fP discards changes.

Settings are stored in INI-style configuration files.  By default, settings are
read from \fI/etc/minttyrc\fP and \fI~/.minttyrc\fP.  Additional config files
can be specified using the \fB--config\fP command line option.  These are read
in order, with settings in later files overriding those in earlier ones.
Configuration changes are saved to the last config file, usually
\fI~/.minttyrc\fP.

The following sections explain the settings on each pane of the options
dialog.
For each setting, its name in the config file is shown in parentheses,
along with its default value, e.g. Columns=80.
For multiple-choice settings, the value representing each choice in the config
file is shown.


.SS Looks
Settings affecting mintty's appearance.

.TP
\fBColours\fP
Clicking on one of the buttons here opens the colour selection dialog.
In the config file, colours are represented as comma-separated RGB triples
with decimal 8-bit values (i.e. ranging from 0 to 255).

.RS
.PD 0
.IP "\- \fBForeground\fP (ForegroundColour=191,191,191)
.IP "\- \fBBackground\fP (BackgroundColour=0,0,0)
.IP "\- \fBCursor\fP (CursorColour=191,191,191)
.RE

.TP
\fBUse system colours instead\fP (UseSystemColours=0)
If this checkbox is ticked, the Windows-wide colour settings are used instead of
the colours chosen above.
(These are the same colours as used for example in Notepad.)

.TP
\fBTransparency\fP (Transparency=0)
Window transparency level, with the following choices:

.RS
.PD 0
.IP "\- \fBOff\fP (0)"
.IP "\- \fBLow\fP (1)"
.IP "\- \fBMedium\fP (2)"
.IP "\- \fBHigh\fP (3)"
.IP "\- \fBGlass\fP (-1)"
.RE

The \fBGlass\fP option is only available on Vista and above with desktop
compositing enabled.
To make this reasonably usable, the glass colour needs to be set to be as dark
as possible in the Windows control panel: choose \fIPersonalize\fP from the
desktop context menu, click on \fIWindow Color\fP, turn the color intensity up
to the maximum, show the color mixer, and turn the brightness down to black.

.TP
\fBOpaque when focused\fP (OpaqueWhenFocused=0)
Enable to make the window opaque when it is active (to avoid background
distractions when working in it).

.TP
\fBCursor\fP (CursorType=2)
The following cursor types are available:

.RS
.PD 0
.IP "\- \fBBlock\fP (0)"
.IP "\- \fBUnderscore\fP (1)"
.IP "\- \fBLine\fP (2)"
.RE

.TP
\fBCursor blink\fP (CursorBlinks=1)
If enabled, the cursor blinks at the rate set in the Windows Keyboard control
panel.


.SS Text
Settings controlling text display.

.TP
\fBFont selection\fP
Clicking on the \fBSelect\fP button opens a dialog where the font and its
properties can be chosen.
In the config file, this corresponds to the following entries:

.RS
.PD 0
.IP "\- \fBFont\fP (Font=Lucida Console)"
.IP "\- \fBStyle\fP (FontIsBold=0)"
.IP "\- \fBSize\fP (FontHeight=10)"
.RE

.TP
\fBSmoothing\fP (FontQuality=0)
Select the amount of font smoothing from the following choices:

.RS
.PD 0
.IP "\- \fBDefault\fP (0): Use Windows setting"
.IP "\- \fBNone\fP (1): With all the jaggies"
.IP "\- \fBPartial\fP (2): Greyscale anti-aliasing"
.IP "\- \fBFull\fP (3): Subpixel anti-aliasing (ClearType)"
.RE

.TP
\fBShow bold as bright\fP (BoldAsBright=1)
By default, text with the ANSI bold attribute set is displayed with
increased brightness.
Alternatively, it can be shown using a bold font, which tends to look better
with black-on-white text.
Additionally, this option controls how the 'half-bright' (or 'dim') text
attribute is displayed: if it is on, half-bright text is
shown with halved foreground colour brightness, otherwise, it is shown
with the foreground colour blended with the background colour.

.TP
\fBAllow blinking\fP (AllowBlinking=0)
ANSI text blinking is diabled by default, on the grounds that blinking
text is a crime against aesthetic decency.

.TP
\fBLocale\fP (Locale=)
The locale setting consists of a lowercase two-letter or three-letter language
code followed by a two-letter country code, for instance \fBen_US\fP or
\fBzh_CN\fP.  The Windows default system and user locales are shown in the
drop-down list for this setting.  Alternatively, the language-neutral "C"
locale can be selected.

If no locale is set here, which is the default, the locale and character set
specified via the environment variables \fILC_ALL\fP, \fILC_CTYPE\fP or
\fILANG\fP are used instead.

If a locale is set, however, it will override any environment variable setting:
\fILC_ALL\fP and \fILC_CTYPE\fP are cleared, while \fILANG\fP is set according
to the chosen locale and character set.

.TP
\fBCharacter set\fP (Charset=)
The character set to be used for encoding input and decoding output.
If no locale is set, this setting is ignored.

While changing the character set takes effect immediately for text input and
ouput, it does not affect the processes already running in mintty.
This is because the environment variables of a running process cannot be
changed from outside that process.
Therefore mintty needs to be restarted for a character set change to take full
effect.


.SS Keys
Settings controlling keyboard behaviour.

.TP
\fBCtrl+LeftAlt is AltGr\fP (CtrlAltIsAltGr=0)
The AltGr key on non-US Windows systems is a strange beast: pressing it is
synonymous with pressing the left Ctrl key and the right Alt key at the
same time, and Windows programs usually treat any Ctrl+Alt combination as
AltGr.

Some programs, however, chief among them Microsoft's very own Office, do not
treat Ctrl+LeftAlt as AltGr, so that Ctrl+LeftAlt combinations can be used in
command shortcuts even when a key has an AltGr character binding.

By default, mintty follows Office's approach, because a number of terminal
programs make use of Ctrl+Alt shortcuts.
The "standard" Windows behaviour can be restored by ticking the checkbox here.

The setting makes no difference for keys without AltGr key bindings
(e.g. any key on the standard US layout).

.TP
\fBBackspace sends ^H\fP (BackspaceSendsBS=0)
By default, mintty sends \fB^?\fP as the keycode for the backspace key.
If this option is enabled, \fB^H\fP is sent instead.
This also changes the Ctrl+Backspace code from \fB^_\fP to \fB^?\fP.

.TP
\fBMenu and Full Screen shortcuts\fP (WindowShortcuts=1)
Checkbox for enabling the \fBAlt+Space\fP and \fBAlt+Enter\fP shortcuts.

.TP
\fBSwitch window shortcuts\fP (SwitchShortcuts=1)
Checkbox for enabling the \fBCtrl+Tab\fP and \fBCtrl+Shift+Tab\fP shortcuts
for switching between mintty windows.

.TP
\fBZoom shortcuts\fP (ZoomShortcuts=1)
Checkbox for enabling the font zooming shortcuts \fBCtrl+plus/minus/zero\fP.

.TP
\fBModifier for scrolling\fP (ScrollMod=1)
The modifier key that needs to be pressed together with the arrow up/down, Page Up/Down, or Home/End keys to access the scrollback buffer.
The default is \fBShift\fP.
The \fBOff\fP setting disables scrolling with keyboard shortcuts.

.RS
.PD 0
.IP "\- \fBShift\fP (1)"
.IP "\- \fBCtrl\fP (4)"
.IP "\- \fBAlt\fP (2)"
.IP "\- \fBOff\fP (0)"
.RE

.TP
\fBPage Up/Down scroll without modifier\fP (PgUpDnScroll=0)
If this is enabled, the scrollback buffer can be accessed using the Page Up/Down
keys without pressing the 'modifier for scrolling' selected above.
If the modifier is pressed anyway, plain Page Up/Down keycodes are sent to the
application.
This option does not affect the arrow keys and Home/End keys.


.SS Mouse
Settings controlling mouse support.

.TP
\fBCopy on select\fP (CopyOnSelect=0)
If enabled, the region selected with the mouse is copied to the clipboard as
soon as the mouse button is released, thus emulating X Window behaviour.

.TP
\fBCopy as rich text\fP (CopyAsRTF=1)
If this option is enabled, which it is by default, text is copied to the
clipboard in rich text format (RTF) in addition to plain text format.
RTF preserves colours and styles when pasting text into applications that
support it, e.g. word processors.

.TP
\fBClicks place command line cursor\fP (ClicksPlaceCursor=0)
If enabled, the command line cursor can be placed by pressing the left
mouse button.
This works by sending the number of cursor keycodes needed to get to the
destination.

.TP
\fBRight click action\fP (RightClickAction=0)
Action to take when the right mouse button is pressed.
If this is set to \fBPaste\fP, the middle button extends the selection region.

.RS
.PD 0
.IP "\- \fBPaste\fP (1): Paste the clipboard contents.
.IP "\- \fBExtend\fP (2): Extend the selected region.
.IP "\- \fBShow menu\fP (0): Show the context menu.
.RE

.TP
\fBDefault click target\fP (ClicksTargetApp=1)
This applies to application mouse mode, i.e. when the application activates
xterm-style mouse reporting.
In that mode, mouse clicks can be sent either to the application to process
as it sees fit, or to the window for the usual actions such as select and paste.

.RS
.PD 0
.IP "\- \fBWindow\fP (0)
.IP "\- \fBApplication\fP (1)
.RE

.TP
\fBModifier key for overriding default\fP (ClickTargetMod=1)
The modifier key selected here can be used to override the click target in
application mouse mode.
With the default settings, clicks are sent to the application and Shift needs
to be held to trigger window actions instead.

The \fBOff\fP setting disables overriding.

.RS
.PD 0
.IP "\- \fBShift\fP (1)"
.IP "\- \fBCtrl\fP (4)"
.IP "\- \fBAlt\fP (2)"
.IP "\- \fBOff\fP (0)"
.RE


.SS Output
Settings for output devices other than the screen.

.TP
\fBPrinter\fP (Printer=)
The ANSI standard defines control sequences for sending text to a printer,
which are used by some terminal applications such as the mail reader
\fBpine\fP.
The Windows printer to send such text to can be selected here.
By default, printing is disabled.

.TP
\fBBell\fP
The three checkboxes here determine what effects the bell character \fB^G\fP
has.
Taskbar highlighting, which is enabled by default, changes the colour of
mintty's taskbar entry in case its window is not active already.

.RS
.PD 0
.IP "\- \fBPlay Sound\fP (BellSound=0)"
.IP "\- \fBFlash Screen\fP (BellFlash=0)"
.IP "\- \fBHighlight in taskbar\fP (BellTaskbar=1)"
.RE

.TP
\fBTERM\fP (Term=xterm)
The TERM variable setting at mintty startup.
Choices available from the dropdown list are \fBxterm\fP, \fBxterm-256color\fP,
and \fBvt100\fP.
This setting has no effect on mintty's terminal emulation, but it tells
applications what features to expect.
The \fBxterm-256color\fP setting enables 256-color mode in some applications,
but may not be recognised at all by others, which is why plain \fBxterm\fP
is the default.

.TP
\fBAnswerback\fP (Answerback=)

The answerback string is sent in response to the \fB^E\fP (ENQ) character.
By default, this is empty.


.SS Window
Window properties.

.TP
\fBColumns\fP (Columns=80)
Default width of the window, in character cells.

.TP
\fBRows\fP (Rows=24)
Default height of the window, in character cells.

.TP
\fBCurrent size\fP
Pressing this button sets the default width and height to the window's
current size.

.TP
\fBShow scrollbar\fP (Scrollbar=1)
Show the scrollbar for accessing the scrollback buffer.

.TP
\fBScrollback lines\fP (ScrollbackLines=10000)
The maximum number of lines to keep in the scrollback buffer.

.TP
\fBAsk for exit confirmation\fP (ConfirmExit=1)
If enabled, ask for confirmation when the close button or \fIAlt+F4\fP is 
pressed and the command invoked by mintty still has child processes.
This is intended to help avoid closing programs accidentally.


.SH KEYCODES

The Windows keyboard layout is used to translate alphanumeric and symbol key
presses into characters, which means that the keyboard layout can be switched
using the standard Windows mechanisms for that purpose.
\fBAltGr\fP combinations, dead keys, and input method editors (IMEs) are
all supported.

Should the available keyboard layouts lack required features,
Microsoft's \fBKeyboard Layout Creator\fP (MSKLC), available from
\fIhttp://www.microsoft.com/Globaldev/tools/msklc.mspx\fP,
can be used to create custom keyboard layouts.

For other keys, mintty sends xterm keycodes as described at
\fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP, with a few
minor changes and additions.

Caret notation is used to show control characters.
See \fIhttp://en.wikipedia.org/wiki/Caret_notation\fP for an explanation.


.SS Alt and Meta

As is customary with PC keyboards, the \fBAlt\fP key acts as the so-called
\fBMeta\fP modifier.
When it is held down while pressing a key or key combination, the keycode is
prefixed with an escape character, unless noted otherwise in the keycode tables
in the following sections.

Encoding the meta modifier by setting the top bit of a character instead
of prefixing it with the escape character is not supported, because that
does not work for character codes beyond 7-bit ASCII.


.SS AltGr

The right \fBAlt\fP key, which is labelled \fBAltGr\fP on most non-US
keyboards, allows to type additional characters on many keyboard layouts.
When the keyboard layout does not have a keycode for an AltGr combination,
the AltGr key is instead treated as Alt instead.

The 'Ctrl+LeftAlt is AltGr' setting allows Ctrl+LeftAlt combinations to
also be treated as AltGr.


.SS Ctrl

For key combinations involving \fBCtrl\fP, the key combination's character code
without the \fBCtrl\fP is looked up in the Windows keyboard layout (whereby
AltGr or Shift may be involved).  If that character corresponds to a control
character, the control character will be sent to the application.
For example, \fBCtrl+]\fP sends \fC^]\fP.

If the keyboard layout does not yield a character from the table below, the
key's "virtual keycode" is tried instead, which usually corresponds to the US
keyboard layout.  This allows control characters to be entered when using a
non-Latin keyboard layout.

If Shift is held in addition to a control character combination, the
corresponding character from the so-called C1 control character set is sent.
The C1 control characters are shown as Unicode codepoints in the table below.  

How exactly C1 control characters are sent depends on the selected character
set.
In ISO-8859 character sets, they are encoded as single bytes, e.g. \\x81 for
U+0081.
With UTF-8, they are encoded as two-byte sequences, which effectively means
that the character code is prefixed with a \\xC2 byte, so for example U+0081
becomes \\xC2\\x81.
C1 codepoints that are not supported by the character set are sent by prefixing
the corresponding ASCII control character with an ESC character, e.g.
\fC^[^A\fP.

.RS
.TS
tab(#) nospaces;
LI    LB    LB
LB    LfC   L.
Key  #Ctrl #Ctrl+Shift
@    #^@   #U+0080
A    #^A   #U+0081
B    #^B   #U+0082
\fR...
Y    #^Y   #U+0099
Z    #^Z   #U+009A
[    #^[   #U+009B
\\   #^\\  #U+009C
]    #^]   #U+009D
^    #^^   #U+009E
\(ul #^_   #U+009F
/    #^_   #U+009F
?    #^?   #U+00FF
.TE
.RE


.SS Special keys

The keys here send the usual control characters, but there are a few
mintty-specific additions that make combinations with modifier keys
available as separate keycodes.

.RS
.TS
tab(#) nospaces;
LI        LB    LB    LB    LB
LB        LfC   LfC   LfC   L.
Key      #plain#Shift#Crtl #Ctrl+Shift
Tab      #^I   #^[[Z #^[[1;5I#\fC^[[1;6I
Space    #\fRSP#\fRSP#^@   #U+0080
Escape   #^[   #\fRU+009B
Pause    #^]   #\fRU+009C
Break    #^\(rs#\fRU+009D
Enter    #^M   #^J   #^^   #U+009E
Back     #^?   #^?   #^_   #U+009F
.TE
.RE

\fBPause\fP and \fBBreak\fP usually share a key, whereby \fBCtrl\fP has to be
pressed to get the \fBBreak\fP function.


.SS Modifier key encodings

Where the modifier keys \fBShift\fP, \fBAlt\fP and \fBCtrl\fP are not handled
as described in the sections above, they are encoded as a one-digit number that
becomes part of the keycode.
To obtain that number, add the numbers for each pressed modifier to 1:

.RS
.PD 0
.IP "\- \fBShift\fP: 1
.IP "\- \fBAlt  \fP: 2
.IP "\- \fBCtrl \fP: 4
.RE

For example, \fBShift+Ctrl\fP would be encoded as the number \fB6\fP (1+1+4).
Modifiers are not double-counted if, for example, both Shift keys are pressed.

The modifier code is shown as \fIm\fP in the following sections.


.SS Number and symbol keys

Number and symbol key combinations that are not handled either by the Windows
keyboard layout or by the Ctrl key processing described above, are assigned the
keycodes shown here.

.RS
.TS
tab(#) nospaces;
LI   LB
LB   LfC.
Key #modified
*   #^[[1;\fIm\fPj
+   #^[[1;\fIm\fPk
,   #^[[1;\fIm\fPl
-   #^[[1;\fIm\fPm
\.  #^[[1;\fIm\fPn
/   #^[[1;\fIm\fPo
0   #^[[1;\fIm\fPp
1   #^[[1;\fIm\fPq
\fR...
8   #^[[1;\fIm\fPx
9   #^[[1;\fIm\fPy
.TE
.RE

(These are VT220 application keypad codes with added modifier.)


.SS Cursor keys

Cursor keycodes without modifier keys depend on whether "application cursor key
mode" (controlled by the DECCKM sequence) is enabled.
Application cursor mode is ignored if any modifier keys are down, and the
modifier code is inserted into the keycode as shown.
The \fBHome\fP and \fBEnd\fP keys are considered cursor keys.

.RS
.TS
tab(#) nospaces;
LI    LB    LB    LB
LB    LfC   LfC   LfC.
Key  #plain#app  #modified
Up   #^[[A #^[OA #^[[1;\fIm\fPA
Down #^[[B #^[OB #^[[1;\fIm\fPB
Left #^[[D #^[OD #^[[1;\fIm\fPD
Right#^[[C #^[OC #^[[1;\fIm\fPC
Home #^[[H #^[OH #^[[1;\fIm\fPH
End  #^[[F #^[OF #^[[1;\fIm\fPF
.TE
.RE


.SS Editing keys

There is no special application mode for the remaining four keys in the block
of six that is usually situated above the cursor keys.

.RS
.TS
tab(#) nospaces;
LI     LB    LB
LB     LfC   LfC.
Key   #plain#modified
Ins   #^[[2~#^[[2;\fIm\fP~
Del   #^[[3~#^[[3;\fIm\fP~
PgUp  #^[[5~#^[[5;\fIm\fP~
PgDn  #^[[6~#^[[6;\fIm\fP~
.TE
.RE


.SS Function keys

\fBF1\fP through \fBF4\fP send numpad-style keycodes, because they
emulate the four PF keys above the number pad on the VT100 terminal.
The remaining function keys send codes that were introduced with
the VT220 terminal.

.RS
.TS
tab(#) nospaces;
LI  LB     LB
LB  LfC    LfC.
Key#plain #modified
F1 #^[OP  #^[[1;\fIm\fPP
F2 #^[OQ  #^[[1;\fIm\fPQ
F3 #^[OR  #^[[1;\fIm\fPR
F4 #^[OS  #^[[1;\fIm\fPS
F5 #^[[15~#^[[15;\fIm\fP~
F6 #^[[17~#^[[17;\fIm\fP~
F7 #^[[18~#^[[18;\fIm\fP~
F8 #^[[19~#^[[19;\fIm\fP~
F9 #^[[20~#^[[20;\fIm\fP~
F10#^[[21~#^[[21;\fIm\fP~
F11#^[[23~#^[[23;\fIm\fP~
F12#^[[24~#^[[24;\fIm\fP~
.TE
.RE


.SS Alt+Numpad

The Windows Alt+Numpad method for entering character codes is supported,
whereby the \fBAlt\fP key has to be held while entering the character's
Unicode codepoint.
If the first digit entered is a zero, the codepoint is interpreted as octal,
otherwise as decimal.
The codepoint is encoded using the selected codepage before it is sent.


.SS Mousewheel

In xterm mouse reporting modes, the mousewheel is treated is a pair of mouse
buttons.
However, the mousewheel can also be used for scrolling in applications such as
\fIless\fP that do not support xterm mouse reporting but that do use the
alternate screen.
Under those circumstances, mousewheel events are encoded as cursor up/down
or page up/down keys.
See the cursor keycode and editing keycodes above for details.

The number of line up/down events sent per mousewheel notch depends on
the relevant Windows setting on the \fBWheel\fP tab of the \fBMouse\fP
control panel.
Page up/down codes can be sent by holding down \fBShift\fP while scrolling.
The Windows wheel setting can also be set to always scroll by a whole screen
at a time.


.SH CONTROL SEQUENCES

Most of the xterm control sequences documented at \fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP are supported.
Please report incompatibilities or unimplemented sequences as bugs.

This section lists control sequences implemented in mintty that are not
supported by xterm.


.SS Escape keycode

There are two settings controlling the keycode sent by the escape key.

The first controls application escape key mode, where the escape key sends a 
keycode that allows applications such as vim to tell it apart from the escape
character appearing at the start of many other keycodes, without resorting to
a timeout mechanism. This setting also applies to the Alt key when that is
pressed on its own.

.RS
.TS
tab(#) nospaces;
LB        LB          LB
LfC       L           LfC.
sequence #mode       #keycode
^[[?7727l#normal     #^[ or ^\(rs
^[[?7727h#application#^[O[
.TE
.RE

When application escape key mode is off, the escape key can be be configured
to send \fB^\\\fP instead of the standard and default \fB^[\fP.
This allows the escape key to be used as one of the special keys in the
terminal line settings (see stty(1)), which is not possible with \fB^[\fP,
as that appears as the first character in many other keycodes.

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       LfC.
sequence #keycode
^[[?7728l#^[
^[[?7728h#^\(rs
.TE
.RE


.SS Shortcut override mode

When shortcut override mode is on, all shortcut key combinations are sent to
the application instead of triggering window commands.

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       LfC.
sequence #override
^[[?7783l#off
^[[?7783h#on
.TE
.RE


.SS Mousewheel reporting

Mintty includes support for sending mousewheel events to an application without
having to enable full xterm mouse reporting, which takes over all mouse events
and isn't supported by every application.

Mousewheel reporting only happens on the \fIalternate screen\fP.
On the primary screen, the mousewheel scrolls the scrollback buffer.

The following two sequences enable or disable mousewheel reporting.
It is enabled by default.

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       L.
sequence #reporting
^[[?7786l#disabled
^[[?7786h#enabled
.TE
.RE

By default, mousewheel events are reported as cursor key presses, which enables
mousewheel scrolling in applications such as \fIless\fP without requiring any
configuration.
Alternatively, mousewheel reporting can be switched to \fBapplication mousewheel
mode\fP, where the mousewheel sends its own separate keycodes that allow
an application to treat the mousewheel differently from cursor keys:

.RS
.TS
tab(#);
LB        LfC.
line up  #^[Oa
line down#^[Ob
page up  #^[[1;2a
page down#^[[1;2b
.TE
.RE

Application mousewheel mode is controlled by these sequences:

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       L.
sequence #mode
^[[?7787l#cursor
^[[?7787h#application
.TE
.RE


.SS Ambiguous width reporting

Applications can ask to be notified when the width of the so-called
"ambiguous width" character category changes due to the user changing font.

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       L.
sequence #reporting
^[[?7700l#disabled
^[[?7700h#enabled
.TE
.RE

When enabled, \fC^[[1W\fP is sent when changing to an "ambiguous narrow"
font and \fC^[[2W\fP is sent when changing to an "ambiguous wide" font.


.SS Font size 

These OSC sequences can be used to set and query font size:

.RS
.TS
tab(#) nospaces;
LB                  LB
LfC                 L.
sequence            #font size
^[]7770;?^G         #query
^[]7770;\fInum\fP^G #set to \fInum\fP
^[]7770;+\fInum\fP^G#increase by \fInum\fP
^[]7770;-\fInum\fP^G#decrease by \fInum\fP
^[]7770;^G          #default
.TE
.RE

As usual, OSC sequences can also be terminated with \fC^[\\\fP (ST) instead
of \fC^G\fP.
When the font size is queried, a sequence that would restore the current size
is sent, terminated with ST: \fC^[]7700;\fInum\fP^[\\\fR.


.SS Locale

The locale and charset used by the terminal can be queried or changed using
these sequences introduced by urxvt:

.RS
.TS
tab(#) nospaces;
LB                  LB
LfC                 L.
sequence           #locale
^[]701;?^G        #query
^[]701;\fIloc\fP^G#set to \fIloc\fP
^[]701;^G         #default
.TE
.RE

The locale string used here should take the same format as in the locale
environment variables such as \fILANG\fP.
When the locale is queried, a sequence that would set the current locale 
is sent, e.g. \fC^[]701;C.UTF-8^[\\\fP.
An empty \fIloc\fP string selects the locale configured in the options or the
environment.


.SS Cursor style

The VT510 DECCSUSR sequence can be used to control cursor shape and blinking.

.RS
\fC^[[ \fIarg\fC \fISP\fC q\fR

.TS
tab(#) nospaces;
LI  LB         LB
LfC L          L.
arg#shape     #blinking
0  #default   #default
1  #block     #yes
2  #block     #no
3  #underscore#yes
4  #underscore#no
5  #line      #yes
6  #line      #no
.TE
.RE


.SH TIPS

A few tips on setting up mintty and other programs.


.SS Shortcuts

The Cygwin package for mintty installs a shortcut in the Windows start menu
under \fIAll Programs/Cygwin\fP.
It starts mintty with a '-' as its only argument, which tells it to invoke
the user's default shell as a login shell.

Shortcuts are also a convenient way to start mintty with additional options
and different commands.
For example, shortcuts for access to remote machines can be created by
invoking \fIssh\fP.
The command simply needs to be appended to the target field of the shortcut
(in the shortcut's properties):

.RS
Target:  \fCC:\\Cygwin\\bin\\mintty.exe \f(CB/bin/ssh server\fR
.RE

The working directory for the session can be set in the "Start In:" field.
(But note that the bash login profile cd's to the user's home directory.)
Another convenient feature of shortcuts is the ability to assign global
shortcut keys.

Cygwin provides the \fBmkshortcut\fP utility for creating shortcuts from the
command line.
See its manual page for details.


.SS Starting mintty from folder context menus

Cygwin's \fBchere\fP package can be used to create a folder context menu
item for mintty in Windows Explorer.
This allows one to right click on a folder and open a shell in that folder.

The following command will create a "Bash Prompt Here" for the current user.
See \fIchere\fP(1) for all the options.

.RS
\fCchere -i -c -t mintty\fP
.RE


.SS Starting mintty from a batch file

In order to start mintty from a batch file it needs to be invoked through the
\fIstart\fP command.
This avoids the batch file's console window staying open while mintty is
running.
For example:

.RS
\fCstart mintty -\fP
.RE


.SS Environment variables

Unfortunately Windows shortcuts do not allow the setting of environment
variables.
Variables can be set globally though via a button on the
\fBAdvanced\fP tab of the \fBSystem Properties\fP.
Those can be reached by right-clicking on \fBComputer\fP, selecting
\fBProperties\fP, then \fBAdvanced System Settings\fP.

Alternatively, global variables can be set using the \fIsetx\fP command
line utility.
This comes pre-installed with some versions of Windows but is also available 
as part of the freely downloadable \fBWindows 2003 Resource Kit Tools\fP.

Another way to set variables for the program to be run in \fBmintty\fP is by
invoking it through the \fBenv\fP command, e.g.:

.RS
\fCmintty /bin/env DISPLAY=:0 /bin/ssh -X server\fP
.RE


.SS The CYGWIN variable

The \fBCYGWIN\fP environment variable is used to control a number of settings
for the Cygwin runtime system.
Many of them apply to the Cygwin console only, but others can be useful
with any Cygwin process.
See \fIhttp://www.cygwin.com/cygwin-ug-net/using-cygwinenv.html\fP for details.


.SS Changing the ANSI colours

A number of settings can be controlled through terminal control sequences,
including the colour values for the 16 ANSI colours.
Here is the xterm sequence for this, whereby \fInum\fP stands for the ANSI
number:

.RS
\fC^[]4;\fInum\fP;\fIred\fP,\fIgreen\fP,\fIblue\fP^G\fR
.RE

For example, to turn yellow (colour 3) up to its full brightness:

.RS
\fCecho $'\\e]4;3;255,255,0\\a'\fP
.RE

Sequences such as this can be included in scripts or on the \fBmintty\fP
command line with the help of \fBsh -c\fP.


.SS Terminal line settings

Terminal line settings can be viewed or changed with the \fBstty\fP utility,
which is installed as part of Cygwin's core utilities package.
Among other things, it can set the control characters used for generating
signals or editing an input line.

See the \fBstty\fP man page for all the details, but here are a few examples.
The commands can be included in shell startup files to make them permanent.

To change the key for deleting a whole word from \fBCtrl+W\fP to
\fBCtrl+Backspace\fP:

.RS
\fCstty werase '^_'\fP
.RE

To use \fBCtrl+Enter\fP instead of \fBCtrl+D\fP for end of file:

.RS
\fCstty eof '^^'\fP
.RE

To use \fBPause\fP and \fBBreak\fP instead of \fBCtrl+Z\fP and \fBCtrl+C\fP for
suspending or interrupting a process, and to also disable the
stackdump-producing SIGQUIT:

.RS
\fCstty susp '^]' swtch '^]' intr '^\\' quit '^-'\fP
.RE

With these settings, the \fBEsc\fP key can also be used to interrupt
processes by setting its keycode to \fB^\\\fP:

.RS
\fCecho $'\e[?7728h'\fP
.RE

The standard escape character \fB^[\fP cannot be used for that purpose
because it appears as the first character in many keycodes.


.SS Readline configuration

Keyboard input for the \fBbash\fP shell and other program that use the
\fBreadline\fP library can be configured with the so-called
\fIinputrc\fP file.
Unless overridden by setting the \fIINPUTRC\fP variable, this is located
at \fI~/.inputrc\fP.

It consists of bindings of keycodes to readline commands, whereby
comments start with a hash character.
The file format is explained fully in the bash manual.

Anyone used to Windows key combinations for editing text might find the
following bindings useful:

.RS
.nf
\fC
# Ctrl+Left/Right to move by whole words
"\\e[1;5C": forward-word
"\\e[1;5D": backward-word

# Ctrl+Backspace/Delete to delete whole words
"\\e[3;5~": kill-word
"\\C-_": backward-kill-word

# Ctrl+Shift+Backspace/Delete to delete to start/end of the line
"\\e[3;6~": kill-line
"\\xC2\\x9F": backward-kill-line # for UTF-8
#"\\x9F": backward-kill-line    # for ISO-8859-x
#"\\e\\C-_": backward-kill-line  # for any other charset

# Alt-Backspace for undo
"\\e\\d": undo
\fP
.fi
.RE

(The Ctrl+Shift+Backspace keycode depends on the selected character set, so
the appropriate binding needs to be chosen.)

Finally, a couple of bindings for convenient searching of the command history.
Just enter the first few characters of a previous command and press
\fBCtrl-Up\fP to look it up.

.RS
.nf
\fC
# Ctrl-Up/Down for searching command history
"\\e[1;5A": history-search-backward
"\\e[1;5B": history-search-forward
\fP
.fi
.RE


.SS Mode-dependent cursor in vim

Using the control sequences for cursor style, the \fBvim\fP editor can be
configured to change cursor depending on mode.
For example, with the following lines in \fI.vimrc\fP, vim will show a block
cursor in normal mode and a line cursor in insert mode:

.RS
.nf
\fC
let &t_ti.="\\e[1 q"
let &t_SI.="\\e[5 q"
let &t_EI.="\\e[1 q"
let &t_te.="\\e[0 q"
\fP
.fi
.RE


.SS Avoiding escape timeout issues in vim

A historical flaw of Unix terminals is that the keycode of the escape key,
i.e. the escape character, also appears at the start of many other keycodes.
This means that on seeing an escape character, an application cannot be sure
whether to treat it as an escape key press or whether to expect more characters
to complete a longer keycode.

Therefore they tend to employ a timeout to decide.  The delay on the escape
key can be annoying though, particularly with the mode-dependent cursor
above enabled.  The timeout approach can also fail on slow connections or a
heavily loaded machine.

Mintty's "application escape key mode" can be used to avoid this by switching
the escape key to an unambiguous keycode.  This will activate it in vim:

.RS
.nf
\fC
let &t_ti.="\\e[?7727h"
let &t_te.="\\e[?7727l"
noremap <Esc>O[ <Esc>
noremap! <Esc>O[ <Esc>
\fP
.fi
.RE


.SH LIMITATIONS

.SS Console Issue

Mintty is not a full replacement for the Windows console window that Cygwin
uses by default.
Like xterm and rxvt, mintty communicates with the child process through a
pseudo terminal device, which Cygwin emulates using Windows pipes.
This means that native Windows command line programs started in mintty see
a pipe rather than a console device.
As a consequence, such programs often disable interactive input. Also,
direct calls to low-level Win32 console functions will fail.
Programs that access the console as a file should be fine though.


.SS Termcap/terminfo

Mintty does not have its own \fItermcap\fP or \fIterminfo\fP entries;
instead, it simply pretends to be an xterm.


.SS Missing xterm features

Mintty is nowhere near as configurable as xterm, and its keycodes
are fixed according to xterm's PC-style keyboard behaviour (albeit
with a number of mintty-specific extensions).
Also, there is no Tektronix 4014 emulation or mouse highlighting mode.


.SH SEE ALSO

\fIbash\fP(1), \fIenv\fP(1), \fIecho\fP(1), \fIstty\fP(1), \fIscript\fP(1),
\fImkshortcut\fP(1), \fIchere\fP(1), \fIlesskey\fP(1), \fIvim\fP(1)

\fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP

\fIhttp://vt100.net\fP


.SH ACKNOWLEDGEMENTS

Mintty is based on PuTTY version 0.60 by Simon Tatham and contributors,
so big thanks to everyone involved.
Thanks also to KDE's Oxygen team for the program icon.


.SH COPYRIGHT

Copyright (C) 2010 Andy Koppe.

Mintty is released under the terms of the the \fIGNU General Public License\fP
version 3 or later.
See \fIhttp://gnu.org/licenses/gpl/html\fP for the license text.

There is NO WARRANTY, to the extent permitted by law.


.SH CONTACT

Please report bugs or suggest enhancements via the issue tracker at
\fIhttp://code.google.com/p/mintty/issues\fP.
Questions can be sent to the discussion group at
\fIhttp://groups.google.com/group/mintty-discuss\fP or
the Cygwin mailing list at \fIcygwin@cygwin.com\fP.


.SH AUTHOR

This manual page was written by Andy Koppe with much appreciated help
from Lee D. Rothstein.
